OnCue Documentation Project Architecture

Overview

This is a Docusaurus 3.9.2-based documentation site for OnCue, a legal technology platform. The project uses a modern static site generation approach with custom React components, MDX content, and a CMS integration for content management.

Key Technologies:

• Docusaurus 3.9.2 - Static site generator
• React 19 - UI library
• MDX - Markdown with JSX support
• TypeScript - Type-safe development
• Decap CMS - Content management system
• GitHub Actions - CI/CD automation

---

Project Structure

oncue-docs-docusaurus/
├── .github/workflows/       # CI/CD automation
│   ├── build.yml           # Build validation workflow
│   └── gen-blocks-drift.yml # Ensures generated files are up-to-date
│
├── site/                   # Main Docusaurus application
│   ├── docs/              # Documentation content (MDX files)
│   │   ├── all-category-pages/  # Category landing pages
│   │   ├── audiovisuals/        # AV-related documentation
│   │   ├── designations/        # Designations documentation
│   │   ├── documents/           # Document management docs
│   │   ├── general/             # General documentation
│   │   ├── media-scripts/       # Media scripts documentation
│   │   ├── notebooks/           # Notebooks documentation
│   │   ├── transcripts/         # Transcripts documentation
│   │   ├── index.mdx           # Homepage/entry point
│   │   ├── FAQ.mdx             # Frequently Asked Questions
│   │   ├── Development.mdx     # Development documentation
│   │   └── Workflow.mdx        # Workflow documentation
│   │
│   ├── src/               # Source code and customizations
│   │   ├── components/    # React components
│   │   │   ├── blocks/    # Custom MDX content blocks
│   │   │   └── HomepageFeatures/ # Homepage components (unused in docs-only mode)
│   │   │
│   │   ├── css/          # Stylesheets
│   │   │   └── custom.css # Extensive custom styling
│   │   │
│   │   ├── clientModules/ # Client-side JavaScript modules
│   │   │   └── print.js   # Print functionality
│   │   │
│   │   ├── theme/        # Docusaurus theme customizations (swizzled)
│   │   │   ├── Root.js    # Root component (image zoom + admin link)
│   │   │   ├── MDXComponents.js # MDX component registration (generated)
│   │   │   ├── DocItem/   # Document item customizations
│   │   │   └── Navbar/    # Navbar customizations
│   │   │
│   │   └── types/        # TypeScript definitions
│   │       └── css.d.ts   # CSS module types
│   │
│   ├── static/           # Static assets
│   │   ├── img/          # Images and icons
│   │   ├── shared/       # Shared assets
│   │   │   ├── oncue-blocks.css # Custom block styling
│   │   │   └── blocks-config.generated.js # Generated block config for CMS
│   │   ├── official_logo_white.svg # Logo for navbar
│   │   └── favicon.ico   # Site favicon
│   │
│   ├── tools/            # Build tools and generators
│   │   └── blocks/       # Block component generator
│   │       ├── generate-blocks.mjs # Generator script
│   │       └── blocks.manifest.json # Block definitions
│   │
│   ├── scripts/          # Utility scripts
│   │   └── localize-images.mjs # Image localization script
│   │
│   ├── docusaurus.config.js # Main Docusaurus configuration
│   ├── sidebars.js       # Sidebar navigation configuration
│   ├── tsconfig.json     # TypeScript configuration
│   └── package.json      # Site dependencies and scripts
│
├── package.json          # Root package.json with site scripts
├── Procfile             # Deployment configuration (Heroku/Railway)
└── .nvmrc               # Node version specification

---

Core Architecture Components

1. Docusaurus Configuration

File: site/docusaurus.config.js

Key Configuration Decisions

Docs-Only Mode:

routeBasePath: '/' // Docs at root, no separate homepage

The site operates in docs-only mode, meaning documentation is served at the root URL (/) rather than under a /docs path. This provides a cleaner URL structure for documentation-focused sites.

Mermaid Support:

markdown: {
  mermaid: true,
},
themes: ['@docusaurus/theme-mermaid']

Enables diagram generation using Mermaid syntax directly in MDX files.

Color Mode:

colorMode: {
  defaultMode: 'light',
  disableSwitch: true,  // Forces light mode only
  respectPrefersColorScheme: false,
}

The site is locked to light mode for consistent branding.

Search Plugin:

plugins: [
  [
    "@easyops-cn/docusaurus-search-local",
    {
      docsRouteBasePath: "/",  // Must match routeBasePath
      hashed: true,
      indexBlog: false,
      language: "en",
      highlightSearchTermsOnTargetPage: true,
      explicitSearchResultPath: true,
    }
  ]
]

Uses a local search plugin instead of Algolia for better control and no external dependencies.

Client Modules:

clientModules: [require.resolve("./src/clientModules/print.js")]

Loads print functionality globally across the site.

---

2. Navigation System

File: site/sidebars.js

Sidebar Structure

The sidebar uses a hybrid approach combining:

1. Top-level item (index/home)
2. Auto-generated categories organized by feature area
3. Root-level documentation pages (FAQ, Development, Workflow)

Category Organization

Each category represents a feature area in the OnCue application:

{
  type: "category",
  label: "Documents",
  className: 'oc-cat-documents',  // Custom CSS class for icons
  link: {type: "doc", id: "all-category-pages/documents"},  // Category landing page
  items: [{type: 'autogenerated', dirName: 'documents'}],  // Auto-discovers docs/documents/*.mdx
}

Icon System: The className (oc-cat-*) maps to CSS custom properties in custom.css that load SVG icons via CSS masks:

.menu__list-item.oc-cat-documents {
  --oc-sidebar-icon: url("../../static/img/icons/docs.svg");
}

Category Hierarchy

1. Documents - Document management features
2. Audiovisuals - Multimedia file handling
3. Transcripts - Transcript synchronization
4. Designations - Designation lists and fine-tuning
5. Media Scripts - Media script generation
6. Notebooks - Notebook functionality
7. Presentation - Presentation features
8. Preferences - Application settings
9. Licensing - License management
10. Advanced - Power user tools
11. Troubleshooting - Help and support items

---

3. Custom MDX Components (Block System)

The project implements a custom component system for rich content blocks in MDX files.

Component Architecture

Block Components: site/src/components/blocks/index.tsx

Available blocks:

• ImageBlock - Single image with optional caption and max-width
• TextImageBlock - Text on left, image on right (adjustable split)
• ImageTextBlock - Image on left, text on right (adjustable split)
• ImageGridBlock - Grid layout (1-3 columns) with caption positioning
• ImageGridItem - Individual grid item
• TwoColBlock - Two-column text layout
• Col - Column wrapper for TwoColBlock
• TextOnly - Text-only block with optional gray background
• BulletList / NumberedList - Styled lists
• Key - Styled keyboard shortcut or UI button reference
• Steps / Step - Vertical numbered steps with custom formatting
• FigmaStatic / FigmaResponsive - Figma embed components

Gray Background System

Most blocks support a grayBg prop for visual separation:

function GrayWrap({grayBg, children}) {
  if (!grayBg) return <>{children}</>;
  return <div className="oc-gray">{children}</div>;
}

Example Usage in MDX

<ImageBlock image="/img/screenshot.png" imageAlt="Example" maxWidth={800}>
  This is a caption for the image
</ImageBlock>

<TextImageBlock image="/img/demo.png" firstCol={60} grayBg>
  Text content on the left side (60% width)
</TextImageBlock>

<ImageGridBlock columns={3} captionPosition="above">
  <ImageGridItem image="/img/1.png">Caption 1</ImageGridItem>
  <ImageGridItem image="/img/2.png">Caption 2</ImageGridItem>
  <ImageGridItem image="/img/3.png">Caption 3</ImageGridItem>
</ImageGridBlock>

---

4. Component Generation System

Generator Script: site/tools/blocks/generate-blocks.mjs

Purpose

Maintains synchronization between:

1. React component definitions
2. MDX component registration
3. Decap CMS configuration

Generated Files

1. src/theme/MDXComponents.js - Registers components for use in MDX
2. static/shared/blocks-config.generated.js - CMS integration metadata

Manifest File

tools/blocks/blocks.manifest.json defines all available blocks:

[
  {
    "name": "ImageBlock",
    "label": "Image Block",
    "group": "Images",
    "template": "<ImageBlock image=\"\" imageAlt=\"\">\n\n</ImageBlock>",
    "allowNested": false,
    "paired": true
  }
]

CI/CD Integration

Workflow: .github/workflows/gen-blocks-drift.yml

Ensures generated files stay synchronized:

- name: Run gen-blocks
  run: npm run gen-blocks

- name: Fail if generated files changed
  run: |
    if ! git diff --exit-code; then
      echo "Generated files are out of date"
      exit 1
    fi

This prevents developers from manually editing generated files.

---

5. Theme Customizations (Swizzled Components)

Docusaurus allows "swizzling" (ejecting and customizing) theme components.

Root Component (src/theme/Root.js)

Responsibilities:

1. Medium-Zoom Integration - Click-to-zoom images
2. Admin Link - Hidden bottom-right edit button for CMS access
3. Global CSS Loading - Loads oncue-blocks.css

Medium-Zoom Implementation:

useEffect(() => {
  const getZoomTargets = () => {
    const candidates = document.querySelectorAll(
      '.theme-doc-markdown img, .markdown img, article img'
    );

    return Array.from(candidates).filter((img) => {
      return (
        !img.closest('.navbar') &&
        !img.closest('.navbar__logo') &&
        !img.closest('.ocIcon')
      );
    });
  };

  const attachZoom = () => {
    const targets = getZoomTargets();
    zoomRef.current = mediumZoom(targets, {
      margin: 80,
      background: 'rgba(0,0,0,0.5)',
    });
  };

  attachZoom();
}, [location.pathname]);

Admin Access Button:

<a href="/admin" className="oc-admin-edit-btn" title="Admin Access" target="_blank">
  <span className="sr-only"></span>
</a>

Styled to be nearly invisible until hover (see custom.css).

Client Module (src/clientModules/print.js)

Adds print functionality to navbar buttons:

document.addEventListener("click", (e) => {
  const link = e.target.closest("a.oc-print-btn");
  if (!link) return;

  e.preventDefault();
  link.blur();
  window.print();
});

---

6. Styling System

Main Stylesheet: site/src/css/custom.css (967 lines)

CSS Architecture

The stylesheet is organized into sections:

1. Root Variables - CSS custom properties for theming
2. Base/Global - HTML and body styles
3. Navbar - Custom navbar styling with purple background
4. Sidebar Menu - Icon system, spacing, collapsible behavior
5. Sidebar Spacing + Caret - Custom expand/collapse UI
6. Root Docs + Dividers - Styling for top-level docs
7. Doc Index Cards - Optional card-based navigation
8. Utilities - Helper classes and z-index management
9. Doc Content Layout - Article width constraints, TOC positioning
10. Markdown Tables - Extensive table styling
11. Link Columns - Multi-column link layouts for category pages
12. Hidden Admin Button - Nearly-invisible edit button
13. Print Styles - Optimized print output (@media print)

Design System Tokens

:root {
  /* Brand Colors */
  --ifm-color-primary: #64128E;  /* OnCue purple */
  --oc-navbar-bg: #64128e;

  /* Layout */
  --ifm-navbar-height: 60px;
  --doc-sidebar-width: 280px;

  /* Typography */
  --ifm-font-family-base: "Source Sans Pro", -apple-system, ...;
  --ifm-font-size-base: 15px;

  /* UI Elements */
  --oc-border: #e5e7eb;
  --oc-hover-bg: #f3f4f6;
  --oc-muted-text: #6b7280;
}

Icon System (CSS Masks)

Icons are rendered using SVG URLs as CSS mask images:

.menu__list-item[class*="oc-cat-"] > .menu__link::before {
  content: "";
  width: 18px;
  height: 18px;
  background-color: var(--oc-sidebar-icon-color);
  mask-image: var(--oc-sidebar-icon);
  mask-repeat: no-repeat;
  mask-position: center;
  mask-size: contain;
}

.menu__link--active,
.menu__link:hover {
  --oc-sidebar-icon-color: var(--ifm-color-primary);
}

This approach allows color changes without separate icon files.

Print Optimization

Comprehensive print styles hide navigation, optimize layout, and add URL printing:

@media print {
  .navbar,
  .theme-doc-sidebar-container,
  .table-of-contents {
    display: none !important;
  }

  .theme-doc-markdown a[href^="http"]:after {
    content: " (" attr(href) ")";
    font-size: 0.85em;
  }

  h1, h2, h3 {
    break-after: avoid-page;
  }
}

---

Build and Deployment

Scripts

Root package.json:

{
  "scripts": {
    "site:dev": "cd site && npm run start",
    "site:build": "cd site && npm run build"
  }
}

Site package.json:

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "serve": "docusaurus serve --host 0.0.0.0 --port ${PORT:-3000}",
    "gen-blocks": "node tools/blocks/generate-blocks.mjs",
    "localize-images": "node scripts/localize-images.mjs"
  }
}

CI/CD Pipeline

Build Validation (.github/workflows/build.yml)

jobs:
  build:
    runs-on: ubuntu-latest
    working-directory: site
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npm run build

Validates that every commit can build successfully.

Generated Files Check (.github/workflows/gen-blocks-drift.yml)

Ensures developers don't forget to regenerate files after modifying the manifest:

- run: npm run gen-blocks
- run: |
    if ! git diff --exit-code; then
      echo "Run: (cd site && npm run gen-blocks)"
      exit 1
    fi

Deployment

Procfile (Heroku/Railway):

web: npx docusaurus serve --port ${PORT:-3000} --host 0.0.0.0

Serves the built site from the site/build/ directory.

Deployment URL: https://support-beta.oncue.tools (from config)

---

Content Management

Decap CMS Integration

While not fully visible in the repository structure, the project includes Decap CMS (formerly Netlify CMS) integration:

• Admin interface accessible at /admin
• Block configuration generated for CMS: static/shared/blocks-config.generated.js
• Custom blocks appear as widgets in the CMS editor

Content Structure

Documentation Files: .mdx format

Example frontmatter:

---
sidebar_position: 1
category: Documents
className: custom-page-class
---

Category Landing Pages: docs/all-category-pages/*.mdx

These provide overview pages that link appears when clicking a category in the sidebar.

---

Key Features and Behaviors

1. Image Zoom Functionality

All content images (excluding navbar/icons) are automatically zoomable via medium-zoom:

• Click any image to zoom
• Dark overlay with configurable margin
• Automatic cleanup on route changes
• Filtered to exclude logos and icons

2. Sidebar Behavior

• Collapsible categories with custom caret icons
• Auto-collapse other categories when one opens
• Hideable sidebar (entire sidebar can be hidden)
• Active item highlighting with purple accent color
• Nested items with visual indent and connecting lines
• Top item (index) styled as prominent purple button

3. Search Functionality

• Local search (no external service required)
• Right-aligned in navbar
• Expandable input on focus
• Term highlighting on result pages
• Indexes only documentation (blog disabled)

4. Responsive Design

Mobile (less than 997px):

• Hamburger menu
• Full-width search
• Hidden "OnCue Documentation" text
• Stacked layouts for two-column blocks

Desktop (great or equal to 997px):

• Persistent sidebar (280px)
• Right-side table of contents
• Centered content with padding
• Multi-column link layouts on category pages

5. Print Output

Optimized print styles:

• Removes navigation, sidebars, TOC
• Displays full URLs for external links
• Prevents page breaks within images/tables
• Forces light background
• Optimizes spacing

---

Data Flow Diagrams

Component Registration Flow

tools/blocks/blocks.manifest.json
          ↓
tools/blocks/generate-blocks.mjs (runs on build)
          ↓
    ┌──────────┴──────────┐
    ↓                     ↓
src/theme/              static/shared/
MDXComponents.js        blocks-config.generated.js
    ↓                     ↓
MDX files render        Decap CMS editor widgets
with custom blocks

Build Process Flow

npm run build
    ↓
1. Generate blocks (gen-blocks script)
    ↓
2. Docusaurus build pipeline
    ↓
3. MDX compilation
    ↓
4. React rendering
    ↓
5. Static HTML generation
    ↓
site/build/ (output directory)

Content Rendering Flow

User requests page
    ↓
Docusaurus routes to doc
    ↓
Loads MDX file from docs/
    ↓
Processes frontmatter (sidebar position, etc.)
    ↓
Compiles MDX → React components
    ↓
Applies theme (Root.js, custom CSS)
    ↓
Renders with:
  - Navbar (logo, search)
  - Sidebar (navigation)
  - Article (MDX content with custom blocks)
  - TOC (on-page navigation)
    ↓
Client-side enhancements:
  - Medium-Zoom attaches
  - Print button activates
  - Search indexes

---

Dependencies

Core Dependencies

{
  "@docusaurus/core": "3.9.2",
  "@docusaurus/preset-classic": "3.9.2",
  "@docusaurus/theme-mermaid": "3.9.2",
  "@easyops-cn/docusaurus-search-local": "0.52.2",
  "@mdx-js/react": "3.0.0",
  "react": "19.0.0",
  "react-dom": "19.0.0",
  "decap-cms-app": "3.10.0",
  "medium-zoom": "1.1.0",
  "clsx": "2.0.0"
}

Dev Dependencies

{
  "@docusaurus/module-type-aliases": "3.9.2",
  "@docusaurus/types": "3.9.2",
  "@types/node": "25.0.10",
  "@types/react": "19.2.8",
  "typescript": "5.9.3",
  "concurrently": "9.2.1"
}

---

Development Workflow

Local Development

# From root
npm run site:dev

# Or directly in site/
cd site
npm run start

Starts development server at http://localhost:3000

Building for Production

# From root
npm run site:build

# Or directly in site/
cd site
npm run build

Outputs to site/build/

Testing Production Build Locally

cd site
npm run serve

Serves built site at http://localhost:3000

Regenerating Block Components

cd site
npm run gen-blocks

Runs after modifying tools/blocks/blocks.manifest.json

Image Localization

cd site
npm run localize-images

Utility for managing localized image assets (if using internationalization).

---

Configuration Details

TypeScript Configuration

File: site/tsconfig.json

Enables TypeScript support for:

• JSX/TSX components
• Type checking in .js files via JSDoc
• Docusaurus module resolution

Node Version Management

File: .nvmrc

Specifies Node.js version (likely 20 or 20.x) for consistency across environments.

Browser Support

From site/package.json:

{
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  }
}

Ensures modern browser compatibility while excluding outdated browsers.

---

Future Considerations

Potential Enhancements

1. Internationalization (i18n)

   • Currently configured for English only
   • localize-images.mjs script suggests planned i18n support

2. Blog Functionality

   • Currently disabled: blog: false
   • Could be enabled for release notes or announcements

3. Homepage Mode

   • Config includes commented option for traditional homepage
   • Would change routeBasePath from / to /docs

4. Dark Mode

   • Currently disabled via disableSwitch: true
   • Color scheme is fully defined but not toggleable

5. Edit This Page Links

   • Currently hidden: .theme-edit-this-page { display: none }
   • Could enable GitHub editing workflow

6. Version Management

   • Docusaurus supports documentation versioning
   • Not currently implemented but available

---

Troubleshooting Common Issues

Generated Files Out of Sync

Error: CI fails with "Generated files are out of date"

Solution:

cd site
npm run gen-blocks
git add .
git commit -m "Regenerate block components"

Build Fails After Component Changes

Check:

1. Is the component exported from src/components/blocks/index.tsx?
2. Is it listed in tools/blocks/blocks.manifest.json?
3. Did you run npm run gen-blocks?
4. Is the component used correctly in MDX files?

Sidebar Not Showing New Category

Check:

1. Does the directory exist in docs/?
2. Is it configured in sidebars.js?
3. Does it have at least one .mdx file?
4. Is frontmatter valid in the MDX files?

Images Not Zoomable

Check:

1. Is the image inside a .theme-doc-markdown container?
2. Is it excluded by the filter (navbar, logo, .ocIcon)?
3. Is Medium-Zoom initialized? (Check browser console)

Search Not Working

Check:

1. Is docsRouteBasePath in plugin config matching routeBasePath in preset?
2. Did the build complete successfully?
3. Are search index files generated in build/ directory?

---

Summary

The OnCue documentation site is a sophisticated Docusaurus implementation featuring:

• Custom component system for rich MDX content with automated registration
• Extensive styling customizations including custom navbar, sidebar icons, and responsive layouts
• CMS integration via Decap CMS for non-developer content editing
• Build automation ensuring code generation stays synchronized
• Print optimization for professional document output
• Enhanced UX features like image zoom and local search
• Robust CI/CD validating every change

The architecture prioritizes maintainability (generated code), content authoring (custom blocks + CMS), and branding (extensive custom styling) while leveraging Docusaurus's powerful static site generation capabilities.

---

Quick Reference

Key Files by Purpose

Purpose	File Path
Main config	site/docusaurus.config.js
Sidebar navigation	site/sidebars.js
Custom styles	site/src/css/custom.css
Custom blocks	site/src/components/blocks/index.tsx
Block manifest	site/tools/blocks/blocks.manifest.json
Block generator	site/tools/blocks/generate-blocks.mjs
Root customization	site/src/theme/Root.js
MDX registration	site/src/theme/MDXComponents.js (generated)
Print handler	site/src/clientModules/print.js
Build workflow	.github/workflows/build.yml
Deployment config	Procfile

Common Commands

# Development
npm run site:dev              # Start dev server
cd site && npm run start      # Alternative

# Building
npm run site:build            # Production build
cd site && npm run build      # Alternative

# Utilities
cd site && npm run gen-blocks     # Regenerate block config
cd site && npm run serve          # Serve production build locally
cd site && npm run localize-images # Localize images

# Docusaurus utilities
cd site && npm run clear      # Clear cache
cd site && npm run swizzle    # Eject/customize theme components

---

Document Version: 1.0 Last Updated: 2026-02-20 Docusaurus Version: 3.9.2 Node Version: ≥20.0